<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta charset="UTF-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1"/>
  <meta name="version" content="0.3.0"/>
  <meta name="series" content="0.3"/>
  <meta name="subject" content="Kconfig module"/>
  <meta name="title" content="Kconfig Module"/>
  <meta name="copyright" content="2020-2023 the build2 authors"/>
  <meta name="license" content="GPLv2"/>

  <title>The build2 Kconfig Module</title>

  <style type="text/css">
/* file      : common.css
 * license   : MIT; see accompanying LICENSE file
 */

html
{
  font-family: "Helvetica Neue", Helvetica, "Segoe UI", Arial, freesans, sans-serif;
  font-weight: normal;
  font-size: 18px;
  line-height: 1.4em;
  letter-spacing: 0.01em;

  color: #292929;
}

body {margin: 0;} /* There is non-0 default margin for body. */

/* See notes on what's going on here. */
body {min-width: 17em;}
@media only screen and (min-width: 360px)
{
  body {min-width: 19em;}
}

/*
 * Header (optional).
 */

#header-bar
{
  width: 100%;

  background: rgba(0, 0, 0, 0.04);
  border-bottom: 1px solid rgba(0, 0, 0, 0.2);

  padding: .4em 0 .42em 0;
  margin: 0 0 1.4em 0;
}

#header
{
  /* Same as in #content. */
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em;

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;

  width: 100%;
  display: table;
  border: none;
  border-collapse: collapse;
}

#header-logo, #header-menu
{
  display: table-cell;
  border: none;
  padding: 0;
  vertical-align: middle;
}

#header-logo {text-align: left;}
#header-menu {text-align: right;}

/* These overlap with #header's margin because of border collapsing. */
#header-logo {padding-left: .4em;}
#header-menu {padding-right: .4em;}

#header-logo a
{
  color: #000;
  text-decoration: none;
  outline: none;
}
#header-logo a:visited {color: #000;}
#header-logo a:hover, #header-logo a:active {color: #000;}

#header-menu a
{
  font-size: 0.889em;
  line-height: 1.4em;
  text-align: right;
  margin-left: 1.2em;
  white-space: nowrap;
  letter-spacing: 0;
}

#header-menu a
{
  color: #000;
  outline: none;
}
#header-menu a:visited {color: #000;}
#header-menu a:hover, #header-menu a:active
{
  color: #3870c0;
  text-decoration: none;
}

/* Flexbox-based improvements though the above works reasonably well. */
#header-menu-body
{
  width: 100%;

  display: -webkit-inline-flex;
  display: inline-flex;

  -webkit-flex-flow: row wrap;
  flex-flow: row wrap;

  -webkit-justify-content: flex-end;
  justify-content: flex-end;
}

/* Whether we want it (and at which point) depends on the size of the menu. */
/*
@media only screen and (max-width: 567px)
{
  #header-menu-body
  {
    -webkit-flex-direction: column;
    flex-direction: column;
  }
}
*/

/*
 * Content.
 */

#content
{
  max-width: 41em;
  margin: 0 auto 0 auto;
  padding: 0 .4em 0 .4em; /* Space between text and browser frame. */

  -webkit-box-sizing: border-box;
  -moz-box-sizing: border-box;
  box-sizing: border-box;
}

/*
 * Footer (optional).
 */

#footer
{
  color: #767676;
  font-size: 0.7223em;
  line-height: 1.3em;
  margin: 2.2em 0 1em 0;
  text-align: center;
}

#footer a
{
  color: #767676;
  text-decoration: underline;
}
#footer a:visited {color: #767676;}
#footer a:hover, #footer a:active {color: #3870c0;}

/* Screen size indicator in the footer. The before/after content is in case
   we don't have any content in the footer. Margin is to actually see the
   border separate from the browser frame. */

/*
#footer:before {content: "\A0";}
#footer:after {content: "\A0";}

#footer
{
  border-left: 1px solid;
  border-right: 1px solid;
  margin-left: 1px;
  margin-right: 1px;
}

@media only screen and (max-width: 359px)
{
  #footer {border-color: red;}
}

@media only screen and (min-width: 360px) and (max-width: 567px)
{
  #footer {border-color: orange;}
}

@media only screen and (min-width: 568px) and (max-width: 1023px)
{
  #footer {border-color: blue;}
}

@media only screen and (min-width: 1024px)
{
  #footer {border-color: green;}
}
*/

/*
 * Common elements.
 */

p, li, dd {text-align: justify;}
.code {text-align: left;} /* Manually aligned. */
pre {text-align: left;}   /* If it is inside li/dd. */

/* Notes. */

.note
{
  color: #606060;
}

div.note
{
  margin: 2em 0 2em 0; /* The same top/bottom margings as pre box. */

  padding-left: 0.5em;
  border: 0.25em;
  border-left-style: solid;
  border-color: #808080;

  page-break-inside: avoid;
}

div.note :first-child {margin-top:    0;}
div.note :last-child  {margin-bottom: 0;}

span.note::before {content: "[Note: "}
span.note::after  {content: "]"}

/* Links. */
a
{
  color: #3870c0;
  /*color: #4078c0;*/
  text-decoration: none;
}

a:hover, a:active
{
/*color: #006fbf;*/
/*color: #0087e7;*/
  text-decoration: underline;
}

a:visited
{
/*color: #003388;*/
  color: #00409c;
}

/* Standard paragraph. */

p, pre {margin: 1em 0 1em 0;}

/* Standard lists. */
ul, ol, dl {margin: 1em 0 1em 0;}
ul li, ol li {margin: 0 0 .4em 0;}
ul li {list-style-type: circle;}
dl dt {margin: 0 0 0 0;}
dl dd {margin: 0 0 .6em 1.8em;}

code, pre
{
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
  font-size: 0.92em;
  letter-spacing: 0;
}

pre {white-space: pre-wrap;}
@media only screen and (max-width: 567px)
{
  pre {word-break: break-all;}
}

/* Use page rather than system font settings. */
input
{
  font-family: inherit;
  font-weight: inherit;
  font-size:   inherit;
  line-height: inherit;
}

/* file      : pre-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css. */

pre
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* file      : code-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Note: see also p-code-box.css if changing anything here. */

code
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .2em .32em .18em .32em;
}

/* file      : p-code-box.css
 * license   : MIT; see accompanying LICENSE file
 */

/* This is the pre-like paragraph produced by CLI for code-only fragments. */

/* Note: see also pre-box.css. */

.code
{
  background-color: rgba(0, 0, 0, 0.05);
  border-radius: 0.2em;
  padding: .8em .4em .8em .4em;
  margin: 2em -.4em 2em -.4em; /* Use margins of #content. */
}

/* Undo code-box.css inside .code. */
.code code
{
  background-color: transparent;
  border-radius: 0;
  padding: 0;
}

/* file      : toc.css
 * license   : MIT; see accompanying LICENSE file
 */

table.toc
{
  border-style      : none;
  border-collapse   : separate;
  border-spacing    : 0;

  margin            : 0.2em 0 0.2em 0;
  padding           : 0 0 0 0;
}

table.toc tr
{
  padding           : 0 0 0 0;
  margin            : 0 0 0 0;
}

table.toc * td, table.toc * th {
  border-style      : none;
  margin            : 0 0 0 0;
  vertical-align    : top;
}

table.toc * th
{
  font-weight       : normal;
  padding           : 0 0.8em 0 0;
  text-align        : left;
  white-space       : nowrap;
}

table.toc * table.toc th
{
  padding-left      : 1em;
}

table.toc * td
{
  padding           : 0 0 0 0;
  text-align        : left;
}

table.toc * td.preface
{
  padding-left      : 1.35em;
}

/* file      : intro.css
 * license   : MIT; see accompanying LICENSE file
 */

/* Bases:
 *
 * common.css
 * pre-box.css
 * code-box.css
 *
 */

#content
{
  max-width: 43.6em;
  padding-left: 3em; /* Reserve for headings. */
}

h1
{
  font-weight: normal;
  font-size: 2em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -1.4em;
}

h1.preface
{
  margin-left: -.56em;
}

h2
{
  font-weight: normal;
  font-size: 1.556em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.8em;
}

h3
{
  font-weight: normal;
  font-size: 1.3em;
  line-height: 1.4em;
  margin: 1.6em 0 .6em -.2em;
}

/* Title page */

#titlepage {
  margin: 0 0 4em 0;
  border-bottom: 1px solid black;
}

#titlepage .title {
  font-weight: normal;
  font-size: 2.333em;
  line-height: 1.4em;
  letter-spacing: 0;
  text-align: center;
  margin: 2em 0 2em 0;
}

#titlepage p {
  font-size: 0.889em;
  line-height: 1.4em;
  margin: 2em 0 .6em 0;
}

  </style>

</head>
<body>
<div id="content">

  <div id="titlepage">
    <div class="title">The <code>build2</code> Kconfig Module</div>

    <p id="revision">Revision <code>0.3.0</code>, June 2023<br/>
    This revision of the document describes the <a href="https://build2.org"><code>build2</code></a>
    Kconfig module <code>0.3.X</code> series.</p>

    <p>Copyright &#169; 2020-2023 the build2 authors.<br/>
    Permission is granted to copy, distribute and/or modify this document
    under the terms of the GPLv2 license.</p>
  </div>

  <h1>Table of Contents</h1>

  <table class="toc">
    <tr><td class="preface" colspan="2"><a
href="#preface">Preface</a></td></tr>
    <tr><th>1</th><td><a href="#intro">Introduction</a>
      <table class="toc">
        <tr><th>1.1</th><td><a href="#intro-kconfig">What is
Kconfig?</a></td></tr>
        <tr><th>1.2</th><td><a href="#intro-kconfig-module">What is
<code>build2</code> Kconfig module?</a></td></tr>
      </table>
    </td></tr>
    <tr><th>2</th><td><a href="#iface-func">Interface and Functionality</a>
      <table class="toc">
        <tr><th>2.1</th><td><a href="#iface-func-conf-method">Configuration
Methods</a></td></tr>
        <tr><th>2.2</th><td><a href="#iface-func-conf-load">Configuring and
Loading</a></td></tr>
        <tr><th>2.3</th><td><a href="#iface-func-ext-macro">External Kconfig
Macro Variables</a></td></tr>
      </table>
    </td></tr>
    <tr><th>3</th><td><a href="#lang">Kconfig Language</a>
      <table class="toc">
        <tr><th>3.1</th><td><a href="#lang-option">Option
(<code>config</code>)</a>
          <table class="toc">
            <tr><th>3.1.1</th><td><a href="#lang-option-prompt-help">Prompt
and Help</a></td></tr>
            <tr><th>3.1.2</th><td><a href="#lang-option-type-default">Type,
Default Value, and Range</a></td></tr>
            <tr><th>3.1.3</th><td><a
href="#lang-option-dep">Dependencies</a></td></tr>
            <tr><th>3.1.4</th><td><a href="#lang-option-rev-dep">Reverse
Dependencies</a></td></tr>
            <tr><th>3.1.5</th><td><a
href="#lang-option-expr">Expressions</a></td></tr>
          </table>
        </td></tr>
        <tr><th>3.2</th><td><a href="#lang-menu">Menu
(<code>menu</code>)</a></td></tr>
        <tr><th>3.3</th><td><a href="#lang-choice">Choice
(<code>choice</code>)</a></td></tr>
        <tr><th>3.4</th><td><a href="#lang-comment">Comment
(<code>comment</code>)</a></td></tr>
        <tr><th>3.5</th><td><a href="#lang-source">Source
(<code>source</code>)</a></td></tr>
        <tr><th>3.6</th><td><a href="#lang-macro">Macro Language</a></td></tr>
        <tr><th>3.7</th><td><a href="#lang-helper">Helper
Options</a></td></tr>
        <tr><th>3.8</th><td><a href="#lang-mod">Modularity
Support</a></td></tr>
        <tr><th>3.9</th><td><a href="#lang-back-compat">Backwards
Compatibility</a></td></tr>
      </table>
    </td></tr>
  </table>
  <h1 id="preface" class="preface">Preface</h1>

  <p>This document describes the <code>build2</code> Kconfig module. It starts
  with an introduction to the Linux kernel configuration system (Kconfig) and
  the <code>build2</code> Kconfig module. The next chapter expands on that and
  describes the integration of Kconfig into the <code>build2</code>
  configuration model in more detail.</p>

  <p>The remainder of the document serves as a guide to the Kconfig language
  with examples based on the <a
  href="https://cppget.org/kconfig-hello"><code>kconfig-hello</code></a>
  package. Besides this guide, see also the official <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html">Kconfig
  Language</a> and <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html">Kconfig
  Macro Language</a> documentation as well as the <a
  href="https://docs.zephyrproject.org/latest/guides/kconfig/tips.html">Kconfig
  Tips and Best Practices</a> from the Zephyr project.</p>

  <h1 id="intro">1 Introduction</h1>

  <p>This chapter provides a brief overview of the Linux kernel configuration
  system (Kconfig) and the functionality provided by the <code>build2</code>
  Kconfig module. Its aim is to show how everything fits and works together
  based on a customary "<i>Hello, World!</i>" example.</p>

  <h2 id="intro-kconfig">1.1 What is Kconfig?</h2>

  <p>Kconfig is the configuration system of the Linux kernel. Over the years
  it has evolved into a sophisticated <a
  href="https://gsd.uwaterloo.ca/sites/default/files/vm-2013-berger.pdf">variability
  modeling language</a> and a toolset that are used by the Linux kernel to
  manage over ten thousand configuration options. It is also increasingly
  being used by other projects that need to manage complex configurations.</p>

  <p>The Kconfig system consists of the following main parts:</p>

  <ul>
  <li>The configuration definition language.</li>

  <li>The configuration management tools.</li>

  <li>The configuration values format.</li>
  </ul>

  <p>The <i>configuration definition language</i>, or the Kconfig language for
  short, defines a hierarchy of menus containing configuration options as well
  as relationships between them. Traditionally, configuration definitions are
  stored in files called <code>Kconfig</code> (with a capital <code>K</code>).
  Here is a simple configuration containing two options:</p>

  <pre>config FANCY
        bool "Fancy options"
        help
          Enable more fancy configuration options.

config GREETING
        string "Custom greeting"
        default "Hello"
        depends on FANCY
        help
          Custom string to use as a greeting.</pre>

  <div class="note">
  <p>While the examples in this document assume a UNIX-like operation system,
  they should work with minimal modifications on Windows.</p>
  </div>

  <p>To create and manage configurations, the Kconfig system includes a number
  of tools called <i>configurators</i>. The most prominent of those are
  <code>kconfig-conf</code> which provides a terminal-based
  question-and-answer configuration method, <code>kconfig-mconf</code> which
  provides a terminal-based menu configuration method based on a curses
  library, and <code>kconfig-qconf</code> which provides a graphical
  configuration method based on Qt. The <code>kconfig-conf</code> configurator
  also provides a number of non-interactive configuration methods (default,
  random, etc), support for updating old configurations to new definitions
  (both interactively and non), as well as other configuration management
  facilities (creation of default configurations, etc).</p>

  <p>Given the above configuration definition saved in the
  <code>Kconfig</code> file, we can run one of the configurators to create a
  new configuration. For example:</p>

  <pre>$ kconfig-conf Kconfig
*
* Main menu
*
Fancy options (FANCY) [N/y/?] (NEW) y
  Custom greeting (GREETING) [Hello] (NEW) Hi
#
# configuration written to .config
#</pre>

  <p>The <i>configuration values</i> are saved into a file that is
  traditionally called <code>.config</code> though this naming convention is
  not as universal as for the definition file (<code>Kconfig</code>). If we
  examine the <code>.config</code> file produced by the above command, we will
  see the following:</p>

  <pre>#
# Automatically generated file; DO NOT EDIT.
# Main menu
#
CONFIG_FANCY=y
CONFIG_GREETING="Hi"</pre>

  <p>The Kconfig system is best suited for complex configuration requirements
  where user input is needed at least in some situations (for example, new
  platforms, custom/optimized configurations, etc). Some of its more advanced
  features include:</p>

  <ul>
  <li>String, integer, and choice configuration options in addition to
  boolean.</li>

  <li>Direct (<code>depends&#160;on</code>) and reverse (<code>select</code>,
  <code>imply</code>) option relationships.</li>

  <li>Grouping into sub-menus and multi-file definitions
  (<code>source</code>).</li>

  <li>Make-like macro substitution in the definition language.</li>

  <li>Sophisticated set of tools for managing configurations.</li>
  </ul>

  <h2 id="intro-kconfig-module">1.2 What is <code>build2</code> Kconfig
  module?</h2>

  <p>The <code>build2</code> Kconfig module provides the ability to use the
  Linux kernel configuration system to configure <code>build2</code> projects.
  Specifically, it integrates the execution of one of the Kconfig
  configurators into the <code>build2</code> <code>configure</code>
  meta-operation and loads the resulting configuration file presenting its
  values as <code>kconfig.*</code> Buildfile variables. We can then use these
  <code>kconfig.*</code> values to make decisions in <code>buildfiles</code>,
  <code>testscripts</code>, and/or propagate them to our source code, similar
  to <code>config.*</code> values (<a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#proj-config">Project
  Configuration</a>).</p>

  <p>As an example, let's see what it takes to add the Kconfig configuration
  shown in the previous section to a simple <code>build2</code> project. As a
  first step, let's create the <code>libhello</code> library using <a
  href="https://build2.org/bdep/doc/bdep-new.xhtml"><code><b>bdep-new(1)</b></code></a>:</p>

  <pre>$ bdep new -l c++ -t lib --no-init libhello
$ cd libhello</pre>

  <p>Next we copy the <code>Kconfig</code> definition file from the previous
  section into the <code>libhello/build/</code> subdirectory:</p>

  <pre>$ cp ../Kconfig build/</pre>

  <p>Finally, we edit <code>libhello/build/bootstrap.build</code> and load the
  <code>kconfig</code> module. Here is what the new
  <code>bootstrap.build</code> could look like:</p>

  <pre>project = libhello

using version
using config
using kconfig
using test
using install
using dist</pre>

  <div class="note">
  <p>The <code>kconfig</code> module is part of the standard pre-installed
  <code>build2</code> modules and no extra integration steps are required
  other than the <code>using</code> directive in
  <code>bootstrap.build</code>.</p>
  </div>

  <p>Now if we configure our project, we will see the familiar prompt:</p>

  <pre>$ b configure
kconfig build/config.kconfig.new
*
* libhello 0.1.0-a.0.19700101000000
*
Fancy options (FANCY) [N/y/?] (NEW) y
  Custom greeting (GREETING) [Hello] (NEW) Hi
save build/config.build
mv build/config.kconfig.new build/config.kconfig</pre>

  <p>From other diagnostics we can gather that the configuration file was
  saved as <code>build/config.kconfig</code>. <span class="note">The reason
  for first saving it as <code>config.kconfig.new</code> is explained in the
  next chapter.</span> We can confirm that its contents are similar to what we
  have already seen:</p>

  <pre>$ cat build/config.kconfig
#
# Automatically generated file; DO NOT EDIT.
# libhello 0.1.0-a.0.19700101000000
#
CONFIG_FANCY=y
CONFIG_GREETING="Hi"</pre>

  <div class="note">
  <p>The only difference in this file (as well as in the above prompt) is the
  replacement of <code>Main menu</code> with <code>libhello
  0.1.0-a.0.19700101000000</code>. As the name suggests, this is the title of
  the main menu which is the root of the Kconfig menu hierarchy. Customarily,
  it is set to the project name and version which the <code>kconfig</code>
  module does automatically. However, it can also be set to a custom value
  with the <code>kconfig.kconfig.title</code> variable, as discussed
  later.</p>
  </div>

  <p>By default the <code>kconfig</code> module uses the terminal-based
  question-and-answer configurator. It's a conservative choice that will work
  in most circumstances and is built into the module, so the presence of the
  <code>kconfig-conf</code> executable is not required. However, we can use
  the <code>config.kconfig</code> variable to select a different configurator.
  For example, we can reconfigure our project using the graphical
  <code>kconfig-qconf</code> configurator <span class="note">This requires the
  presence of the <code>kconfig-qconf</code> executable</span>:</p>

  <pre>$ b configure config.kconfig=qconf</pre>

  <p>The <code>CONFIG_*</code> values from the configuration file are made
  available as <code>kconfig.&lt;project>.*</code> variables in
  <code>buildfiles</code> with the configuration option name converted to the
  lower case. For example, we can examine our values by adding the following
  <code>info</code> directives at the beginning of
  <code>libhello/buildfile</code>:</p>

  <pre>info "fancy: $kconfig.libhello.fancy"
info "greeting: $kconfig.libhello.greeting"</pre>

  <p>If we now update our <code>libhello</code> project, we should see the
  following output:</p>

  <pre>$ b
libhello/buildfile:1:1: info: fancy: true
libhello/buildfile:2:1: info: greeting: Hi
...</pre>

  <p>The Kconfig configuration is also reported at a sufficiently high
  verbosity level (<a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#proj-config-report">Configuration
  Report</a>). For example:</p>

  <pre>$ b configure -v
kconfig libhello@/tmp/libhello/
  fancy      true
  greeting   Hi</pre>

  <div class="note">
  <p>The configuration values (<code>fancy</code> and <code>greeting</code>)
  used in this example are the same as what's shown in <a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#proj-config">Project
  Configuration</a> and the same mechanisms for post-processing and
  propagating configuration values apply here; in most examples from that
  chapter you can simply replace <code>config.libhello.*</code> with
  <code>kconfig.libhello.*</code>.</p>

  <p>Note, however, that if a non-bool option is disabled (for example,
  because its dependencies are unsatisfied), then the corresponding
  <code>kconfig.*</code> variable will be <code>null</code>. At the same time,
  the <a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#module-in"><code>in</code>
  module</a> treats a <code>null</code> substitution as an error unless a
  fallback value is specified with the <code>in.null</code> variable. As a
  result, if non-bool <code>kconfig.*</code> variables are used in the
  <code>.in</code> file substitutions, then it is a good idea to specify the
  fallback, for example:</p>

  <pre>h{config}: in{config}
{
  # Instruct the in rule to substitute null with empty.
  #
  in.null = ''
}</pre>

  <p>See <a
  href="https://cppget.org/kconfig-hello"><code>kconfig-hello</code></a> for a
  complete example that uses these mechanisms.</p>
  </div>

  <p>Analogous to <code>configure</code>, the standard <code>disfigure</code>
  meta-operation removes the Kconfig configuration, or, more precisely, moves
  it to <code>config.kconfig.old</code>. For example:</p>

  <pre>$ b disfigure
mv build/config.kconfig build/config.kconfig.old
rm build/config.build</pre>

  <p>And that's pretty much all we have to do to integrate Kconfig-based
  configuration management into our project. One last touch would be to add
  <code>config.kconfig</code> to <code>build/.gitignore</code>, next to
  <code>config.build</code>:</p>

  <pre>/config.build
/config.kconfig*
...</pre>

  <div class="note">
  <p>We've used a wildcard after <code>config.kconfig</code> to also ignore
  intermediate <code>config.kconfig.new</code> files (discussed later) as well
  as the <code>config.kconfig.old</code> file where Kconfig configurators
  traditionally save the previous configuration.</p>
  </div>

  <p>The next chapter, <a href="#iface-func">Interface and Functionality</a>,
  provides more details on the functionality offered by the
  <code>kconfig</code> module, including the available configurators,
  customization points, etc. For an introduction to the Kconfig language that
  also covers relevant <code>build2</code> integration aspects, refer to <a
  href="#lang">Kconfig Language</a>.</p>

  <h1 id="iface-func">2 Interface and Functionality</h1>

  <p>This chapter provides a more detailed discussion of the
  <code>kconfig</code> module's interface and functionality including its
  integration with the <code>config</code> module's configuration process as
  well as the customization points available to projects that use Kconfig.</p>

  <h2 id="iface-func-conf-method">2.1 Configuration Methods</h2>

  <p>As we have seen in the introduction, the <code>config.kconfig</code>
  variable can be used to select an alternative configurator, such as
  <code>mconf</code> or <code>qconf</code>. This variables also controls a few
  other aspects of producing new or updating an existing configuration which
  together we will call a <i>configuration method</i>. It has the following
  overall structure:</p>

  <p
  class="code"><code>[(<b>new</b>|<b>old</b>)<b>-</b>](<b>def</b>|<b>ask</b>|<b>reask</b>|<b>mconf</b>|<b>qconf</b>|<b>env</b>)
  [...]</code></p>

  <p>The optional first component controls the reuse of existing
  <code>config.kconfig</code>. If <code>new</code> is specified, then the
  configuration is created from scratch (with existing
  <code>config.kconfig</code>, if exists, saved as
  <code>config.kconfig.old</code>). If <code>old</code> is specified, then the
  configuration is created based on existing <code>config.kconfig</code> (with
  what "based" means determined by the second component). In this case, it's
  an error for there to be no existing <code>config.kconfig</code>. If the
  first component is omitted, then existing <code>config.kconfig</code> is
  reused if present (<code>old</code> semantics) and created from scratch
  otherwise (<code>new</code> semantics).</p>

  <p>Given a configuration option definition in the Kconfig file, its value
  can come from the following sources:</p>

  <ol>
  <li>Existing <code>config.kconfig</code> file.</li>

  <li>Default configuration file.</li>

  <li>Default value from the <code>Kconfig</code> file.</li>
  </ol>

  <p>A configuration option that does not have a value in existing
  <code>config.kconfig</code> is referred to as a <i>newly-defined
  configuration option</i>. Naturally, if <code>config.kconfig</code> does not
  exist or is not used (because of the <code>new</code> first component), then
  all options are newly-defined.</p>

  <p>The second component determines the configurator and its mode and has the
  following possible values:</p>

  <dl>
  <dt style="margin-bottom:1em"><code><b>def</b> [<i>file</i>]</code></dt>
  <dd>Set newly-defined configuration options to values from
  <code><i>file</i></code> if specified and to their default values from
  <code>Kconfig</code> otherwise (if some options are missing in
  <code><i>file</i></code>, they are set to default values as well). To reset
  all the configuration options, use <code>new-def</code>.</dd>

  <dt style="margin-bottom:1em"><code><b>ask</b> [<i>file</i>]</code></dt>
  <dd>Ask for values of only newly-defined configuration options. For default
  answers use values from <code><i>file</i></code> if specified and default
  values from <code>Kconfig</code> otherwise.

  <p>Note that if <code>config.kconfig</code> does not exist or is not used
  (<code>new-ask</code>) then this method is equivalent to
  <code>reask</code>.</p></dd>

  <dt style="margin-bottom:1em"><code><b>reask</b> [<i>file</i>]</code></dt>
  <dd>Ask for values of all the configuration options. For default answers use
  values from <code>config.kconfig</code> if exists, from
  <code><i>file</i></code> if specified, and default values from
  <code>Kconfig</code> otherwise.</dd>

  <dt style="margin-bottom:1em"><code><b>mconf</b></code></dt>
  <dd>Present all the configuration options in a menu interface. For default
  answers, use values from <code>config.kconfig</code> if exists and default
  values from <code>Kconfig</code> otherwise.</dd>

  <dt style="margin-bottom:1em"><code><b>qconf</b></code></dt>
  <dd>Present all the configuration options in a graphical interface. For
  default answers, use values from <code>config.kconfig</code> if exists and
  default values from <code>Kconfig</code> otherwise.</dd>

  <dt style="margin-bottom:1em"><code><b>env</b> <i>prog</i>
  [<i>args</i>]</code></dt>
  <dd>Run <code><i>prog</i></code> in the configuration environment
  (<code>KCONFIG_CONFIG</code>, etc) passing the <code>Kconfig</code> file as
  the last argument. For example:

  <pre>config.kconfig="env kconfig-conf --savedefconfig defconfig.kconfig"</pre></dd>
  </dl>

  <div class="note">
  <p>The <code>def</code>, <code>ask</code>, and <code>reask</code> methods
  are implemented as builtins and do not require the presence of the
  <code>kconfig-conf</code> executable.</p>
  </div>

  <p>If no configuration method is specified with <code>config.kconfig</code>,
  then <code>ask</code> is used by default. However, a project may specify a
  different default configuration method as discussed in the next section.</p>

  <div class="note">
  <p>Mapping for some of the <code>kconfig-conf</code> options to the above
  methods:</p>

  <pre>--oldconfig             ask
--oldaskconfig          reask
--olddefconfig          def
--alldefconfig      new-def
--defconfig &lt;file>  new-def &lt;file></pre>

  <p>Note that the following methods have no <code>kconfig-conf</code>
  equivalents:</p>

  <pre>old-def &lt;file>
[re]ask &lt;file></pre>
  </div>

  <p>Another useful application of the <code>env</code> method is the
  generation of random configurations with the <code>kconfig-conf</code>
  <code>--randconfig</code> mode. For example:</p>

  <pre>$ b configure config.kconfig="env kconfig-conf -s --randconfig"
kconfig build/config.kconfig.new
KCONFIG_SEED=0xD6A72753
save build/config.build
mv build/config.kconfig.new build/config.kconfig</pre>

  <p>This can be used to automatically try various configurations, for
  example, by continuously configuring and testing the project in a loop <span
  class="note">This example is UNIX-specific</span>:</p>

  <pre>$ while \
  b configure config.kconfig="env kconfig-conf -s --randconfig" &amp;&amp; \
  b test; do :; done</pre>

  <p>As can be seen on the previous listing, in the <code>--randconfig</code>
  mode, <code>kconfig-conf</code> prints the seed that it used to generate the
  configuration. This seed can be passed back to <code>kconfig-conf</code> as
  an environment variable in order to recreate the same random configuration.
  For example:</p>

  <pre>$ KCONFIG_SEED=0xD6A72753 \
  b configure config.kconfig="env kconfig-conf -s --randconfig"</pre>

  <div class="note">
  <p>Another useful <code>--randconfig</code> environment variable is
  <code>KCONFIG_ALLCONFIG</code> which can be used to specify a configuration
  file containing a subset of options that must be set to specific rather than
  random values.</p>
  </div>

  <h2 id="iface-func-conf-load">2.2 Configuring and Loading</h2>

  <p>As mentioned briefly in the introduction, <code>kconfig</code> acts as a
  second-level configuration mechanism to the builtin support in the form of
  <code>config.*</code> variables and the <code>config</code> module. In
  particular, the <code>kconfig</code> module hooks into the
  <code>configure</code> and <code>disfigure</code> meta-operations of the
  <code>config</code> module providing an integrated configuration process. It
  is also possible to use the <code>config.*</code> variables (as well as
  other Buildfile variables) as inputs to the <code>kconfig</code>
  configuration. This chapter provides more details on how this is achieved
  and the available customization points.</p>

  <p>To understand how <code>kconfig</code> fits in, we begin with an overview
  of the builtin configuration process, that is, what happens when we execute
  the <code>configure</code> meta-operation. While the <code>config</code>
  module is loaded in <code>bootstrap.build</code>, the
  <code>config.build</code> file (if exists) is loaded as a first step of
  loading <code>root.build</code> (more precisely, <code>config.build</code>
  is loaded before any bootstrapped module is initialized, which happens prior
  to loading <code>root.build</code>). After that, <code>root.build</code> and
  the rest of the project are loaded as usual. In particular, during this
  stage, <code>root.build</code> or any other <code>buildfile</code> can
  examine the <code>config.*</code> variables (as loaded from
  <code>config.build</code> and/or specified as command line overrides) and
  cause this stage to fail (for example, using the <code>assert</code>
  directive) if any values are deemed invalid. If, however, loading of the
  project succeeds, the <code>config</code> module saves the new
  <code>config.build</code> file which completes the <code>configure</code>
  meta-operation.</p>

  <p>The important point about this process is that the new configuration is
  saved as the last step, after successfully loading the project. And the
  <code>kconfig</code> module attempts to provide the second-level
  configuration semantics that is consistent with this behavior. Specifically,
  while the <code>kconfig</code> module must also be loaded (bootstrapped) in
  <code>bootstrap.build</code>, it also delays loading
  <code>config.kconfig</code> until later. However, unlike the
  <code>config</code> module, by default, <code>kconfig</code> loads its
  configuration after <code>root.build</code>. This semantics was chosen to
  allow the first-level configuration as well as any other information made
  available by modules loaded in <code>root.build</code> to influence the
  Kconfig configuration. However, we can also load <code>config.kconfig</code>
  at any point in <code>root.build</code> by explicitly loading (initializing)
  the <code>kconfig</code> module. For example, continuing with the
  <code>libhello</code> project from the previous chapter, we could have
  something like this in our <code>root.build</code>:</p>

  <pre>using cxx

using kconfig

if ($kconfig.libhello.fancy &amp;&amp; $cxx.target.class == 'windows')
  fail "have to keep it basic on Windows"</pre>

  <p>Similar to the <code>config</code> behavior, the <code>kconfig</code>
  module also saves the configuration only after the project has successfully
  been loaded. Achieving this semantics, however, is not as straightforward as
  in the <code>config</code> module because the configuration must also be
  made available during the project loading, as discussed above. To implement
  this, <code>kconfig</code> first saves the configuration to a temporary
  file, <code>config.kconfig.new</code>, and then renames it to
  <code>config.kconfig</code> at the end. Specifically, the
  <code>kconfig</code> module performs the following steps during
  <code>configure</code>:</p>

  <dl>
  <dt style="margin-bottom:1em"><code>bootstrap.build</code></dt>
  <dd>Register the post-<code>configure</code> callback with the
  <code>config</code> module.</dd>

  <dt style="margin-bottom:1em"><code>root.build</code></dt>
  <dd>Run the configurator saving the result to
  <code>config.kconfig.new</code>.</dd>

  <dt style="margin-bottom:1em"><code>configure</code></dt>
  <dd>In post-<code>configure</code> rename <code>config.kconfig.new</code> to
  <code>config.kconfig</code>.</dd>
  </dl>

  <p>When not configuring, the <code>kconfig</code> module simply loads
  <code>config.kconfig</code> and verifies it is up-to-date with definitions
  in <code>Kconfig</code>. If that's not the case, for example, because we've
  added or removed a configuration option, then <code>kconfig</code> fails
  suggesting that we reconfigure the project.</p>

  <p>As mentioned in the previous section, a project may specify the default
  configuration method that will be used if not explicitly specified with
  <code>config.kconfig</code>. More precisely, the project may set any of the
  <code>kconfig.kconfig.{configure,reconfigure,retryconfigure}</code>
  variables to select the default method for creating new, updating existing,
  and trying to fix previously created/updated configuration,
  respectively.</p>

  <p>To elaborate, the <code>kconfig.kconfig.configure</code> method is used
  when configuring a project from scratch, without existing
  <code>config.kconfig</code>, while <code>kconfig.kconfig.reconfigure</code>
  is used while reconfiguring a project with existing
  <code>config.kconfig</code>. The <code>kconfig.kconfig.retryconfigure</code>
  method is used when reconfiguring a project with existing
  <code>config.kconfig.new</code>, which normally means that the previous
  (re)configuration attempt has failed or was interrupted. The default values
  for these variables are <code>reask</code>, <code>ask</code>, and
  <code>reask</code>, respectively.</p>

  <div class="note">
  <p>Setting <code>kconfig.kconfig.retryconfigure</code> to a method that does
  not allow the user to adjust every configuration option may result in an
  invalid configuration that can only be fixed by first disfiguring the
  project.</p>
  </div>

  <p>As an example, if we wanted our project to use the default values from
  <code>Kconfig</code> and only use interactive configuration if explicitly
  requested by the user (or if the default configuration turned out to be
  invalid), we could add the following to our <code>root.build</code> before
  loading <code>kconfig</code>:</p>

  <pre>kconfig.kconfig.configure = new-def
kconfig.kconfig.reconfigure = old-def

using kconfig</pre>

  <div class="note">
  <p>Provided this makes sense for your project, it's a good idea to make the
  default configuration method non-interactive. This will allow you to use the
  CI service and, if desired, publish your project to a package repository.
  While interactive default configuration may make sense for an
  <i>end-product</i> kind of projects, for reusable components such as
  libraries a non-interactive default that enables most of the functionality
  is probably the best choice. See <a
  href="https://build2.org/build2/doc/build2-build-system-manual.xhtml#proj-config">Project
  Configuration</a> for background.</p>
  </div>

  <p>What happens if we try to build our project without
  <code>config.kconfig</code>? By default <code>kconfig</code> fails
  suggesting that we configure the project. However, this behavior can be
  altered with the <code>kconfig.kconfig.transient</code> variable. Setting it
  to <code>ask</code> (which is the default), disables the ability to use
  transient configurations. But in the above project it would make sense to
  also use default values for transient configurations, for example:</p>

  <pre>kconfig.kconfig.configure = new-def
kconfig.kconfig.reconfigure = old-def
kconfig.kconfig.transient = def

using kconfig</pre>

  <p>Besides the default values from <code>Kconfig</code> files, another
  common source of default values are <i>default configurations</i>. This
  method becomes more appropriate when we have multiple sets of default
  values, for instance, one per target platform. As an example, let's convert
  the above project to use the default configuration files in the
  <code>defconfig-<i>platform</i>.kconfig</code> form where
  <code><i>platform</i></code> is the target class as supplied by the
  <code>cxx.target.class</code> variable (<code>linux</code>,
  <code>windows</code>, <code>macos</code>, etc). Here are the changes to
  <code>root.build</code>:</p>

  <pre>using cxx

defconfig = $src_root/build/defconfig-$(cxx.target.class).kconfig

kconfig.kconfig.configure = new-def $defconfig
kconfig.kconfig.reconfigure = old-def $defconfig
kconfig.kconfig.transient = def $defconfig

using kconfig</pre>

  <div class="note">
  <p>The <code>build/Kconfig</code> file and files that it sources
  (transitively) as well as <code>build/defconfig*.kconfig</code> are
  automatically added to the distribution and need not be explicitly mentioned
  as prerequisites in <code>buildfiles</code>.</p>
  </div>

  <p>While any Kconfig configuration file can serve as a default
  configuration, normally a minimal version is produced using
  <code>kconfig-conf --savedefconfig</code>. Given a suitably configured
  project, we can extract the corresponding default configuration using the
  <code>env</code> method:</p>

  <pre>$ b configure config.kconfig=\
"env kconfig-conf --savedefconfig defconfig-linux.kconfig"</pre>

  <p>We can also do it manually given just the configuration file, for
  example:</p>

  <pre>$ KCONFIG_CONFIG=config.kconfig \
  kconfig-conf --savedefconfig defconfig-linux.kconfig Kconfig</pre>

  <div class="note">
  <p>If your <code>Kconfig</code> definition file relies on external inputs
  (as discussed next), then with the manual extraction you will also need to
  manually supply such inputs via environment variables.</p>
  </div>

  <h2 id="iface-func-ext-macro">2.3 External Kconfig Macro Variables</h2>

  <p>Selecting the default configuration based on the target platform as shown
  in the previous section is one example of using information from the
  first-level configuration and/or modules loaded before <code>kconfig</code>
  to adjust the Kconfig configuration. It is, however, also possible to modify
  the <code>Kconfig</code> definition file itself based on such information by
  setting external Kconfig macro variables.</p>

  <p>The Kconfig language includes a macro variable facility that can be used
  for textual substitution (see <a href="#lang-macro">Macro Language</a> for
  details). As an example, let's try to improve on our previous attempt to
  only allow fancy options in certain cases. To recap, this is what we
  did:</p>

  <pre>using cxx

using kconfig

if ($kconfig.libhello.fancy &amp;&amp; $cxx.target.class == 'windows')
  fail "have to keep it basic on Windows"</pre>

  <p>Ideally, instead of allowing the user to select the <code>FANCY</code>
  option and then complaining that it can't be selected for certain platforms,
  we would want to make it impossible to select it in the first place when
  configuring for such platforms. As a first step, let's introduce a Kconfig
  macro variable and make the <code>FANCY</code> option depend on its
  value:</p>

  <pre>ENABLE_FANCY := y

config FANCY
        bool "Fancy options"
        depends on $(ENABLE_FANCY)
        help
          Enable more fancy configuration options.

...</pre>

  <p>With this change we can now enable/disable the fancy options by adjusting
  the <code>ENABLE_FANCY</code> Kconfig macro variable. The next step is to
  somehow set it from outside the <code>Kconfig</code> file. With the
  <code>kconfig</code> module we can do that by simply setting the
  corresponding <code>Kconfig.*</code> variable (with a capital
  <code>K</code>) in our <code>buildfile</code>. <span class="note">If
  invoking one of the configurators directly, then such variables are set via
  the environment</span>. In our example, let's remove the
  <code>ENABLE_FANCY</code> assignment from <code>Kconfig</code> and rewrite
  <code>root.build</code> as follows:</p>

  <pre>using cxx

Kconfig.ENABLE_FANCY = ($cxx.target.class != 'windows')

using kconfig</pre>

  <div class="note">
  <p><code>Kconfig.*</code> values of type <code>bool</code> are automatically
  converted from Buildfile <code>true</code>/<code>false</code> to Kconfig
  <code>y</code>/<code>n</code>. Other value types are passed to Kconfig by
  converting to string.</p>
  </div>

  <p>The Kconfig macro variables can be used in many contexts, for example, in
  default values. However, such dynamically-changing Kconfig definitions
  become hard to reason about and can lead to surprises. As a result, it's
  probably wise to limit the use of external variables to disabling options
  and menus rather than altering their definitions.</p>

  <p>A macro substitution referencing a variable that is not set inside the
  <code>Kconfig</code> file nor via the <code>Kconfig.*</code> Buildfile
  variable is an error. The only builtin variable set automatically by the
  <code>kconfig</code> module is <code>SRC_ROOT</code> which contains the
  project's source root directory (the same as the <code>src_root</code>
  Buildfile variable). It is normally used to source (<a
  href="#lang-source">Source</a>) additional <code>Kconfig</code> files, for
  example:</p>

  <pre>source "$(SRC_ROOT)/libhello/Kconfig"</pre>

  <h1 id="lang">3 Kconfig Language</h1>

  <p>Kconfig is a line-oriented language. That is, a construct ends at the end
  of the line unless escaped with line continuation (trailing <code>\</code>).
  The <code>#</code> character starts a comment with everything from this
  character until the end of the line ignored. This character and other
  special characters (quotes, <code>$</code>, etc) can be escaped with a
  backslash.</p>

  <p>Kconfig has single-quoted (<code>'</code>) and double-quoted
  (<code>"</code>) strings with identical semantics. Inside strings, all
  characters except the closing quote and <code>$</code> (macro substitution)
  are treated literally. For example, the following two Kconfig strings are
  the same:</p>

  <pre>"foo \"bar\" \$(baz)"
'foo "bar" \$(baz)'</pre>

  <p>A <code>Kconfig</code> file starts with zero or more macro variable
  assignments (<a href="#lang-macro">Macro Language</a>) followed by zero or
  more Kconfig definitions which may source (<a
  href="#lang-source">Source</a>) other <code>Kconfig</code> files. Each
  definition starts with a keyword. For example:</p>

  <pre># This is a comment.

DEFAULT_GREETING := Hello

config GREETING
        string "Custom greeting"
        default "$(DEFAULT_GREETING)"

source "$(SRC_ROOT)/Kconfig"</pre>

  <p>The following synopsis lists all the available Kconfig definitions with
  the subsequent sections explaining their semantics using examples from the
  <a href="https://cppget.org/kconfig-hello"><code>kconfig-hello</code></a>
  package. For additional background and details see also the official <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html">Kconfig
  Language</a> and <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html">Kconfig
  Macro Language</a> documentation as well as the <a
  href="https://docs.zephyrproject.org/latest/guides/kconfig/tips.html">Kconfig
  Tips and Best Practices</a> from the Zephyr project.</p>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<i>type</i> [<i>prompt</i> [<b>if</b>
  <i>expr</i>]]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>prompt</b> <i>prompt</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>default</b> <i>value</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>range</b> <i>integer</i>
  <i>integer</i> [<b>if</b> <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>select</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>imply</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>help</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>text</i>
  <br/>
  <br/>
  <b>if</b> <i>expr</i>
  <br/>
  ...
  <br/>
  <b>endif</b>
  <br/>
  <br/>
  <b>menu</b> <i>prompt</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>visible if</b> <i>expr</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  ...
  <br/>
  <b>endmenu</b>
  <br/>
  <br/>
  <b>menuconfig</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;...
  <br/>
  <br/>
  <b>choice</b> [<i>symbol</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>optional</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>default</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;...
  <br/>
  ...
  <br/>
  <b>endchoice</b>
  <br/>
  <br/>
  <b>comment</b> <i>prompt</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  <br/>
  <b>source</b> <i>path</i>
  <br/>
  <br/>
  <i>type</i> &#160;&#160;&#160;= <b>bool</b> | <b>string</b> | <b>int</b> |
  <b>hex</b> | <b>tristate</b>
  <br/>
  <i>value</i> &#160;&#160;= (<b>y</b>|<b>n</b>) | <i>string</i> |
  <i>integer</i> | (<b>y</b>|<b>m</b>|<b>n</b>)
  <br/>
  <i>string</i> &#160;= <b>"</b><i>text</i><b>"</b> |
  <b>'</b><i>text</i><b>'</b>
  <br/>
  <i>integer</i> = <i>dec-integer</i> | <b>0x</b><i>hex-integer</i>
  <br/>
  <i>prompt</i> &#160;= <i>string</i>
  <br/>
  <i>path</i> &#160;&#160;&#160;= <i>string</i>
  <br/>
  <br/>
  <i>term</i> = <i>symbol</i> | <i>value</i>
  <br/>
  <i>expr</i> = <i>term</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>=</b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>!=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;</b>
  <i>term</i> &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>></b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;=</b>
  <i>term</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>>=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>(</b> <i>expr</i> <b>)</b>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>!</b> <i>expr</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>&amp;&amp;</b>
  <i>expr</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>||</b>
  <i>expr</i></code></p>

  <h2 id="lang-option">3.1 Option (<code>config</code>)</h2>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<i>type</i> [<i>prompt</i> [<b>if</b>
  <i>expr</i>]]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>prompt</b> <i>prompt</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>default</b> <i>value</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>range</b> <i>integer</i>
  <i>integer</i> [<b>if</b> <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>select</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>imply</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>help</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>text</i>
  <br/>
  <br/>
  <b>if</b> <i>expr</i>
  <br/>
  ...
  <br/>
  <b>endif</b>
  <br/>
  <br/>
  <i>type</i> &#160;&#160;&#160;= <b>bool</b> | <b>string</b> | <b>int</b> |
  <b>hex</b> | <b>tristate</b>
  <br/>
  <i>value</i> &#160;&#160;= (<b>y</b>|<b>n</b>) | <i>string</i> |
  <i>integer</i> | (<b>y</b>|<b>m</b>|<b>n</b>)
  <br/>
  <i>string</i> &#160;= <b>"</b><i>text</i><b>"</b> |
  <b>'</b><i>text</i><b>'</b>
  <br/>
  <i>integer</i> = <i>dec-integer</i> | <b>0x</b><i>hex-integer</i>
  <br/>
  <i>prompt</i> &#160;= <i>string</i>
  <br/>
  <br/>
  <i>term</i> = <i>symbol</i> | <i>value</i>
  <br/>
  <i>expr</i> = <i>term</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>=</b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>!=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;</b>
  <i>term</i> &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>></b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;=</b>
  <i>term</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>>=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>(</b> <i>expr</i> <b>)</b>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>!</b> <i>expr</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>&amp;&amp;</b>
  <i>expr</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>||</b>
  <i>expr</i></code></p>

  <p>The central part of Kconfig is the <i>configuration option</i> definition
  with the rest of the language is mostly serving to organize options into
  sub-menus. A simple <code>Kconfig</code> file may consist of just option
  definitions which all become entries of the implicitly-defined main menu
  (discussed in the next section).</p>

  <p>The option definition starts with the <code>config</code> keyword
  followed by the option name, which in the Kconfig language is called a
  <i>symbol</i>. For example:</p>

  <pre>config IO
        bool "IO support"
        help
          Enable stdin/stdout input/output. Note that if this option
          is disabled, then you won't see any output.</pre>

  <div class="note">
  <p>Other Kconfig documentation often uses the term symbol to mean the
  configuration option, not just its name.</p>
  </div>

  <p>The name is traditionally spelled in upper case and is the same name that
  will end up in the configuration file but prefixed with <code>CONFIG_</code>
  and as a Buildfile variable but converted into lower case and prefixed with
  <code>kconfig.&lt;project>.</code>.</p>

  <p>Following the <code>config</code> keyword and the name we have a number
  of lines that define the option's <i>attributes</i>. They are traditionally
  indented by 8 spaces (or an equivalent TAB). While none of the attributes
  are mandatory, a definition will normally include at least the type and
  usually also the prompt and help, as in the above example.</p>

  <p>A number of attributes support the trailing
  <code>if&#160;<i>expr</i></code> condition. If specified, the attribute only
  applies if the expression evaluates to true (<a
  href="#lang-option-expr">Expressions</a>). Such attributes can also be
  specified multiple times. For example:</p>

  <pre>config GREETING_TEXT
        string "Custom greeting" if GREETING_CUSTOM
        default "Hello" if GREETING_HELLO
        default "Hi"    if GREETING_HI
        default "Howdy" if GREETING_HOWDY
        help
          Custom string to use as a greeting.</pre>

  <p>In this example, the <code>GREETING_TEXT</code> option will only be
  visible if the <code>GREETING_CUSTOM</code> option is selected and the
  default value is chosen based on which <code>GREETING_H*</code> option is
  selected.</p>

  <h3 id="lang-option-prompt-help">3.1.1 Prompt and Help</h3>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<i>type</i> [<i>prompt</i> [<b>if</b>
  <i>expr</i>]]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>prompt</b> <i>prompt</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>help</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>text</i>
  <br/>
  <br/>
  <i>string</i> &#160;= <b>"</b><i>text</i><b>"</b> |
  <b>'</b><i>text</i><b>'</b>
  <br/>
  <i>prompt</i> &#160;= <i>string</i></code></p>

  <p>The configuration option prompt is a short text that describes the option
  to the user while the option help provides a more detailed description. For
  example:</p>

  <pre>config IO
        bool
        prompt "IO support"
        help
          Enable stdin/stdout input/output. Note that if this option
          is disabled, then you won't see any output.</pre>

  <p>If an option has a visible prompt (that is, the prompt is not disabled
  with <code>if&#160;<i>expr</i></code>) and its dependencies are satisfied
  (<a href="#lang-option-dep">Dependencies</a>), then the option is presented
  to the user for customization. For example:</p>

  <pre>$ b configure
IO support (IO) [N/y/?] (NEW) ?

CONFIG_IO:

Enable stdin/stdout input/output. Note that if this option
is disabled, then you won't see any output.

Symbol: IO [=n]
Type  : bool
Defined at kconfig-hello/build/Kconfig:18
  Prompt: IO support
  Location:
    -> Basic options</pre>

  <p>The option prompt can be specified with the <code>prompt</code> attribute
  as in the above example or it can be combined with the type attribute for
  brevity. For example:</p>

  <pre>config IO
        bool "IO support"
        ...</pre>

  <p>This shorter version is customarily preferred unless selecting between
  several prompts with <code>if&#160;<i>expr</i></code>. In both versions the
  prompt text can be specified using either single or double quotes.</p>

  <p>The option help often contains several lines of text and is specified
  indented (customarily with 2 spaces) relative to the line that contains the
  <code>help</code> keyword. The help text ends at the line that has a smaller
  indentation than the first line of the help text.</p>

  <p>While an option with an invisible prompt cannot be modified by the user,
  it can still be modified by other options through reverse dependencies and
  its value is accessible via the corresponding <code>kconfig.*</code>
  variable. An option with an absent prompt that is selected through such
  reverse dependencies is called a <i>helper option</i>. See <a
  href="#lang-helper">Helper Options</a> for more information on their
  use-cases.</p>

  <h3 id="lang-option-type-default">3.1.2 Type, Default Value, and Range</h3>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<i>type</i> [<i>prompt</i> [<b>if</b>
  <i>expr</i>]]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>default</b> <i>value</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>range</b> <i>integer</i>
  <i>integer</i> [<b>if</b> <i>expr</i>]
  <br/>
  <br/>
  <i>type</i> &#160;&#160;&#160;= <b>bool</b> | <b>string</b> | <b>int</b> |
  <b>hex</b> | <b>tristate</b>
  <br/>
  <i>value</i> &#160;&#160;= (<b>y</b>|<b>n</b>) | <i>string</i> |
  <i>integer</i> | (<b>y</b>|<b>m</b>|<b>n</b>)
  <br/>
  <i>string</i> &#160;= <b>"</b><i>text</i><b>"</b> |
  <b>'</b><i>text</i><b>'</b>
  <br/>
  <i>integer</i> = <i>dec-integer</i> | <b>0x</b><i>hex-integer</i></code></p>

  <p>Configuration option type can be <code>bool</code> (boolean),
  <code>string</code>, <code>int</code> (decimal integer), <code>hex</code>
  (hexadecimal integer), and <code>tristate</code>:</p>

  <dl>
  <dt style="margin-top:2em"><code><b>bool</b></code></dt>
  <dd>True or false state. Values of this type are spelled as <code>y</code>
  or <code>n</code>, for example:

  <pre>config FOO
        bool
        default y</pre>

  <p style="margin-bottom:2em">When converted to the <code>kconfig.*</code>
  variables, such values have the <code>bool</code> Buildfile type.</p></dd>

  <dt><code><b>string</b></code></dt>
  <dd>Text string. Values of this type are spelled using either single or
  double quotes, for example:

  <pre>config FOO
        string
        default "foo"</pre>

  <p style="margin-bottom:2em">When converted to the <code>kconfig.*</code>
  variables, such values have the <code>string</code> Buildfile type.</p></dd>

  <dt><code><b>int</b></code></dt>
  <dd>Signed 64-bit decimal integer. Values of this type are spelled as a
  sequence of decimal digits, for example:

  <pre>config FOO
        int
        default 123</pre>

  <p style="margin-bottom:2em">When converted to the <code>kconfig.*</code>
  variables, such values have the <code>int64</code> Buildfile type.</p></dd>

  <dt><code><b>hex</b></code></dt>
  <dd>Unsigned 64-bit hexadecimal integer. Values of this type are spelled as
  a sequence of hexadecimal digits prefixed with <code>0x</code>, for example:

  <pre>config FOO
        hex
        default 0x1ab2c3d4</pre>

  <p style="margin-bottom:2em">When converted to the <code>kconfig.*</code>
  variables, such values have the <code>uint64</code> Buildfile type.</p></dd>

  <dt><code><b>tristate</b></code></dt>
  <dd style="margin-bottom:2em">Like <code>bool</code> but with an extra state
  (<code>m</code>) used to express modularity. See <a
  href="#lang-mod">Modularity Support</a> for details on this
  functionality.</dd>
  </dl>

  <div class="note">
  <p>The <code>kconfig.*</code> variables are overridable which means, similar
  to the first-level configuration, we can temporarily tweak the Kconfig
  configuration (as seen by <code>buildfiles</code>) without reconfiguring the
  project. For example:</p>

  <pre>$ b kconfig.hello.io=false</pre>

  <p>Note, however, that such changes do not go through the usual Kconfig
  processing which, in particular, means no option dependency resolution is
  performed. As a result, care must be taken not to end up with an invalid
  configuration.</p>
  </div>

  <p>The default value for a configuration option can be specified with the
  <code>default</code> attribute. For example:</p>

  <pre>config PUNCT
        string "End of greeting punctuation"
        default "!"
        help
          Character for punctuating the end of the greeting sentence.</pre>

  <p>This value will be used as the suggested answer in interactive
  configurations methods and as a fallback in non-interactive ones (see <a
  href="#iface-func-conf-method">Configuration Methods</a> for details). If no
  default value is specified, <code>n</code> is assumed for <code>bool</code>
  and <code>tristate</code> and empty string for <code>string</code> while
  there is no assumed default for <code>int</code> and <code>hex</code>.</p>

  <div class="note">
  <p>While <code>int</code> and <code>hex</code> options without default
  values are valid, creating a configuration in a way that would require
  default values (for example with the <code>config.kconfig=def</code> method)
  is an error.</p>
  </div>

  <p>Options of type <code>int</code> and <code>hex</code> can also specify
  the expected value range with the <code>range</code> attribute (both ends
  are inclusive). If specified, the user will not be allowed to enter a value
  that is out of this range. For example:</p>

  <pre>config NAME_ASK_MAX
        int "Max times to ask for name"
	default 5
	range 1 10
        help
          Maximum number of times to ask for the name to greet.</pre>

  <h3 id="lang-option-dep">3.1.3 Dependencies</h3>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  <br/>
  <b>if</b> <i>expr</i>
  <br/>
  ...
  <br/>
  <b>endif</b></code></p>

  <p>The <code>depends&#160;on</code> attribute is used to specify a
  dependency of one option on another. Collectively, dependencies determine
  what configurations are valid. For example:</p>

  <pre>config IO
        bool "IO support"

config NAME_ASK
        bool "Ask for name"
        depends on IO</pre>

  <p>If an option's dependency is not satisfied, then the option becomes
  <i>disabled</i>: the user is not prompted for its value and its default
  value is not used. For <code>bool</code> and <code>tristate</code>, the
  disabled option is set to <code>n</code>. For other types, the disabled
  option's value is not set and the corresponding <code>kconfig.*</code>
  variable is <code>null</code>.</p>

  <div class="note">
  <p>We use the term <i>enabled</i>/<i>disabled</i> when we refer to the
  option's state based on its dependencies and <i>visible</i>/<i>invisible</i>
  &#8211; based on its prompt. An option is only presented to the user for
  customization if it is both enabled and visible. If a <code>bool</code>
  option is set to <code>y</code>, we call it <i>selected</i>.</p>
  </div>

  <p>The <code>depends&#160;on</code> attribute can also be used to specify a
  dependency on an expression involving more than one option or non-boolean
  options (see <a href="#lang-option-expr">Expressions</a> for details). For
  example:</p>

  <pre>config IO
        bool "IO support"

config RETRY
        int "Max times to retry"

config NAME_ASK
        bool "Ask for name"
        depends on IO &amp;&amp; RETRY != 0</pre>

  <p>Specifying multiple <code>depends&#160;on</code> attributes is equivalent
  to specifying their expressions with a single <code>depends&#160;on</code>
  attribute combined with <code>&amp;&amp;</code>. For example, this variant
  is equivalent to the above:</p>

  <pre>config NAME_ASK
        bool "Ask for name"
        depends on IO
        depends on RETRY != 0</pre>

  <p>If we have multiple options with the same dependency, then instead of
  repeating the <code>depends&#160;on</code> attribute for each of them we can
  use the <code>if</code>-block for a more succinct result. For example:</p>

  <pre>config IO
        bool "IO support"

if IO

config NAME_ASK
        bool "Ask for name"

config TRACE
        bool "Trace execution"

endif</pre>

  <p>The semantics of the <code>if</code>-block is equivalent to specifying an
  explicit <code>depends&#160;on</code> attribute with the
  <code>if</code>-expression for each entry until <code>endif</code>.</p>

  <h3 id="lang-option-rev-dep">3.1.4 Reverse Dependencies</h3>

  <p class="code"><code><b>config</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>select</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>imply</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]</code></p>

  <p>A reverse dependency is used to <i>select</i> an option from another
  option. For example:</p>

  <pre>config IO
        bool "IO support"

config NAME_ASK
        bool "Ask for name"
        select IO</pre>

  <p>In this example, if <code>NAME_ASK</code> is set to <code>y</code>, then
  <code>IO</code> is forced to <code>y</code> as well.</p>

  <p>Reverse dependencies can only be used with <code>bool</code> and
  <code>tristate</code> options and there are two flavors: strong and
  weak.</p>

  <p>A strong reverse dependency is specified with the <code>select</code>
  attribute. It forces the option specified after the <code>select</code>
  keyword to <code>y</code> whenever the option containing this attribute is
  set to <code>y</code> (for <code>tristate</code> options, the same logic
  applies for <code>m</code>). And by <i>forces</i> we mean just that: it
  disregards unsatisfied dependencies and user selection.</p>

  <p>Note that this forceful nature of strong reverse dependencies often leads
  to puzzling configuration issues. For example, a user may be trying to
  unsuccessfully disable a feature without realizing that it is forced by
  another, seemingly unrelated option. Such issues can be very frustrating and
  time-consuming to figure out and, as a result, the use of reverse
  dependencies on user-visible options is not recommended. Using
  <code>select</code> on invisible options, however, is a useful technique as
  described in <a href="#lang-helper">Helper Options</a>.</p>

  <p>A weak reverse dependency is specified with the <code>imply</code>
  attribute. As the name suggests, it does not force but merely recommends.
  The other option can still be set to <code>n</code> by the user or if any of
  its dependencies are unsatisfied. For example:</p>

  <pre>config IO
        bool "IO support"
        default y
        imply NAME_ASK

config NAME_ASK
        bool "Ask for name"</pre>

  <p>In this example, if the user selects <code>y</code> for <code>IO</code>,
  then the prompt for <code>NAME_ASK</code> will also have <code>y</code> as
  the default answer. However, the user can still disable
  <code>NAME_ASK</code> by answering <code>n</code>. Similarly, if configuring
  non-interactively using the default values
  (<code>config.kconfig=def</code>), then <code>NAME_ASK</code> will be set to
  <code>y</code> because <code>IO</code> is set to <code>y</code> (because of
  its <code>default&#160;y</code> attribute).</p>

  <h3 id="lang-option-expr">3.1.5 Expressions</h3>

  <p class="code"><code><i>value</i> &#160;&#160;= (<b>y</b>|<b>n</b>) |
  <i>string</i> | <i>integer</i> | (<b>y</b>|<b>m</b>|<b>n</b>)
  <br/>
  <i>string</i> &#160;= <b>"</b><i>text</i><b>"</b> |
  <b>'</b><i>text</i><b>'</b>
  <br/>
  <i>integer</i> = <i>dec-integer</i> | <b>0x</b><i>hex-integer</i>
  <br/>
  <br/>
  <i>term</i> = <i>symbol</i> | <i>value</i>
  <br/>
  <i>expr</i> = <i>term</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>=</b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>!=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;</b>
  <i>term</i> &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>></b> <i>term</i>
  &#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>&lt;=</b>
  <i>term</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>term</i> <b>>=</b> <i>term</i>
  &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>(</b> <i>expr</i> <b>)</b>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<b>!</b> <i>expr</i>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>&amp;&amp;</b>
  <i>expr</i> &#160;&#160;&#160;|
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;&#160;<i>expr</i> <b>||</b>
  <i>expr</i></code></p>

  <p>Kconfig expressions are used in a number of option attributes to
  determine visibility, establish dependencies, and to enable default values.
  And as we will see in later sections, they are also used for similar
  purposes in other Kconfig definitions. The result of evaluating an
  expression is boolean <code>y</code> (true) or <code>n</code> (false).</p>

  <div class="note">
  <p>More precisely, Kconfig expressions use the tristate logic with the extra
  <code>m</code> state used to represent modularity. For the evaluation
  purposes, the <code>m</code> state is equivalent to <code>y</code> if
  modules are enabled. See <a href="#lang-mod">Modularity Support</a> for
  details.</p>
  </div>

  <p>Expression alternatives in the above production are listed in the
  decreasing order of precedence. Values in expressions are spelled as in the
  <code>default</code> attribute (<a href="#lang-option-type-default">Type,
  Default Value, and Range</a>).</p>

  <p>A terminal expression consisting of a symbol evaluates to true if the
  corresponding option is of type <code>bool</code> (or <code>tristate</code>)
  and is <code>y</code> (or <code>m</code> and modules are enabled). In this
  context options of all other types always evaluate to <code>n</code>.</p>

  <p>A terminal expression consisting of a value evaluates to true if it is
  either <code>y</code> or <code>"y"</code> (or <code>m</code> or
  <code>"m"</code> and modules are enabled). For example <span
  class="note">See <a href="#iface-func-ext-macro">External Kconfig Macro
  Variables</a> for a more realistic example</span>:</p>

  <pre>ENABLE_FANCY := y

config IO
        bool "IO support"

config FANCY
        bool "Fancy options"
        depends on IO
        depends on $(ENABLE_FANCY)</pre>

  <p>Terminals (symbol or value) can be compared for being equal/unequal
  less/greater, and less-or-equal/greater-or-equal. Finally, sub-expression
  can be grouped with parenthesis, negated, and combined with logical AND and
  OR. For example:</p>

  <pre>FALLBACK_NAME := ...

config IO
        bool "IO support"

config RETRY
        int "Max times to retry"

config NAME_ASK
        bool "Ask for name"
        depends on IO &amp;&amp; (RETRY != 0 || "$(FALLBACK_NAME)" = "")</pre>

  <h2 id="lang-menu">3.2 Menu (<code>menu</code>)</h2>

  <p class="code"><code><b>menu</b> <i>prompt</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>visible if</b> <i>expr</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i>
  <br/>
  ...
  <br/>
  <b>endmenu</b>
  <br/>
  <br/>
  <b>menuconfig</b> <i>symbol</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;...</code></p>

  <p>Menus are used to organize options into a tree-like hierarchy as an aid
  to the user. Normally a menu would contain related options. If a menu
  contains a large number of options, then some of them can be organized into
  sub-menus and so on.</p>

  <p>The menu definition starts with the <code>menu</code> keyword followed by
  the menu prompt. Similar to an option, a menu may specify a number of
  attributes on the following lines. After the menu definition and before the
  matching <code>endmenu</code> keyword, any option, sub-menu, etc., all
  belong to this menu and are collectively called <i>menu entries</i>. For
  example:</p>

  <pre>menu "Basic options"

config IO
        bool "IO support"
        help
          Enable stdin/stdout input/output. Note that if this option
          is disabled, then you won't see any output.

config PUNCT
        string "End of greeting punctuation"
        default "!"
        help
          Character for punctuating the end of the greeting sentence.

endmenu</pre>

  <p>Similar to option prompts, menu prompts are presented to the user during
  option customization. For example:</p>

  <pre>$ b configure
*
* Basic options
*
IO support (IO) [N/y/?] (NEW) y
End of greeting punctuation (PUNCT) [!] (NEW) !!!</pre>

  <p>The menu visibility can be controlled with the
  <code>visible&#160;if</code> attribute. If its expression evaluates to
  false, then neither the menu itself nor any of its entries are presented to
  the user. For example:</p>

  <pre>menu "Fancy options"
        visible if IO

...

endmenu</pre>

  <p>Menu visibility is the extension of the option prompt visibility in that
  an option that belongs to an invisible menu has the same semantics as if it
  had an invisible prompt (<a href="#lang-option-prompt-help">Prompt and
  Help</a>).</p>

  <p>Another attribute of a menu definition is <code>depends&#160;on</code>.
  Specifying this attribute is equivalent to specifying it for every option
  that belongs to this menu, recursively (<a
  href="#lang-option-dep">Dependencies</a>).</p>

  <p>The Kconfig menu hierarchy always starts with an implicitly-defined main
  menu. While it is possible to customize its prompt in the
  <code>Kconfig</code> file using the <code>mainmenu</code> definition,
  customarily it is set to the project name and version which the
  <code>kconfig</code> module does automatically. It can also be customized by
  setting the <code>kconfig.kconfig.title</code> variable in
  <code>root.build</code> before loading the <code>kconfig</code> module.</p>

  <div class="note">
  <p>Specifying <code>mainmenu</code> in the <code>Kconfig</code> file is not
  recommended when used with <code>build2</code> because there can only be one
  such definition thus making the result non-composable. And there are plans
  for the <code>kconfig</code> module to automatically aggregate Kconfig
  configurations of multiple projects into a single configurator
  invocation.</p>
  </div>

  <p>When organizing options into menus we often encounter a pattern where a
  configuration option enables a menu, for example:</p>

  <pre>config FANCY
        bool "Fancy options"
        help
          Enable more fancy configuration options.

menu "Fancy options"
  depends on FANCY

config GREETING
        string "Custom greeting"
        help
          Custom string to use as a greeting.

config NAME_ASK
        bool "Ask for name"
        help
          Ask for the name to greet if it is unspecified on the
          command line.
endmenu</pre>

  <p>Regardless of how we structure this (option outside or inside the menu),
  the user interface will have a separate entry for the option and the menu
  while what we want here is to combine them. To achieve this we use the
  <code>menuconfig</code> hybrid menu/option. For example:</p>

  <pre>menuconfig FANCY
        bool "Fancy options"
        help
          Enable more fancy configuration options.

if FANCY

config GREETING
        string "Custom greeting"
        ...

config NAME_ASK
        bool "Ask for name"
        ...

endif</pre>

  <p>The <code>menuconfig</code> definition has the same semantics and
  attributes as <code>config</code> but additionally establishes a sub-menu
  and treats all the following entries (options, menus) that have a dependency
  on its symbols as sub-menu entries until encountering the first entry
  without such a dependency. The common approach to establish such a
  dependency is to use the <code>if</code>-block as in the example above.</p>

  <div class="note">
  <p>If you are wondering why <code>menuconfig</code> does not use an explicit
  end marker similar to <code>endmenu</code>, you are not alone. It is
  probably a remnant of the automatic menu generation described next.</p>
  </div>

  <p>Even if we didn't use <code>menuconfig</code> in the above example,
  Kconfig would analyze the dependency relationship and generate a menu-like
  structure automatically. Specifically, all the immediately following entries
  that have a dependency on the preceding option are treated as its
  sub-entries and displayed as belonging to this option. What "displayed as
  belonging" means, exactly, depends on the configurator and in some it may be
  indistinguishable from <code>menuconfig</code>.</p>

  <h2 id="lang-choice">3.3 Choice (<code>choice</code>)</h2>

  <p class="code"><code><b>choice</b> [<i>symbol</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>optional</b>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>default</b> <i>symbol</i> [<b>if</b>
  <i>expr</i>]
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;...
  <br/>
  ...
  <br/>
  <b>endchoice</b></code></p>

  <p>Choices are used to restrict the selection to the at most one option from
  a set. In a way, they can be viewed as a variant of the menu concept but
  where instead of all the options the user can select only one.</p>

  <p>The choice definition starts with the <code>choice</code> keyword
  optionally followed by the choice name. Similar to options and menus, a
  choice may specify a number of attributes on the following lines. After the
  choice definition and before the matching <code>endchoice</code> keyword
  comes a number of options (normally two or more) collectively called
  <i>choice options</i>. Choice options can only be of type <code>bool</code>
  and <code>tristate</code>. For example:</p>

  <pre>choice
        prompt "Greeting"
        default GREETING_HELLO
        help
          String to use as a greeting.

config GREETING_HELLO
        bool "\"Hello\""
        select GREETING_BUILTIN

config GREETING_HI
        bool "\"Hi\""
        select GREETING_BUILTIN

config GREETING_HOWDY
        bool "\"Howdy\""
        select GREETING_BUILTIN

config GREETING_CUSTOM
        bool "Custom greeting"

endchoice</pre>

  <p>Given the above choice, the user could be presented with the following
  interface:</p>

  <pre>$ b configure
Greeting
> 1. "Hello" (GREETING_HELLO) (NEW)
  2. "Hi" (GREETING_HI) (NEW)
  3. "Howdy" (GREETING_HOWDY) (NEW)
  4. Custom greeting (GREETING_CUSTOM) (NEW)
choice[1-4?]:</pre>

  <div class="note">
  <p>Choices with <code>tristate</code> options allow selecting multiple
  options provided they are all set to <code>m</code>. See <a
  href="#lang-mod">Modularity Support</a> for details.</p>
  </div>

  <p>Two commonly used choice attributes are <code>default</code> and
  <code>optional</code>. The <code>default</code> attribute is used to specify
  the default selection as shown in the example above. The
  <code>optional</code> attribute makes the choice optional allowing the user
  not to select any of the choice options.</p>

  <div class="note">
  <p>A non-optional choice without a default value will currently result in an
  invalid configuration if configuring non-interactively using the default
  values (<code>config.kconfig=def</code>). As a result, it is recommended to
  always specify default values for non-optional choices.</p>
  </div>

  <p>A choice definition can specify any of the other configuration option
  attributes, however, not all of them make sense in all situations. In
  practice, there are two common patterns of choice usage: a simple choice
  without a name and an optional choice with a name. Here is the overall
  structure of the first pattern (which is also used in the above
  example):</p>

  <pre>choice
        prompt "Prompt text"
        default DEFAULT_OPTION

...

endchoice</pre>

  <p>In the second pattern, the optional choice is given a name that is used
  as a helper (<a href="#lang-helper">Helper Options</a>) to determine whether
  any of the choice options were selected. Such a choice may or may not have
  the default value. Here is its overall structure:</p>

  <pre>choice CHOICE_NAME
       bool "Prompt text"
       optional
       default DEFAULT_OPTION

...

endchoice</pre>

  <p>And here is a concrete example of such a choice:</p>

  <pre>choice NAME_FALLBACK
       bool "Name fallback"
       optional
       help
         Fallback name to use if it is unspecified on the command
         line.

config NAME_ASK
        bool "Ask for name"
        help
          Ask for the name to greet if it is unspecified on the
          command line.

config NAME_DEF
        bool "Use default name"
        help
          Use the default name to greet if it is unspecified on the
          command line.

endchoice</pre>

  <p>At the Buildfile level we can then use
  <code>kconfig.&lt;project>.name_fallback</code> to determine if any of the
  choice options were selected, for example:</p>

  <pre>if $kconfig.hello.name_fallback
{
  if $kconfig.hello.name_ask
    ...

  if $kconfig.hello.name_def
    ...
}</pre>

  <h2 id="lang-comment">3.4 Comment (<code>comment</code>)</h2>

  <p class="code"><code><b>comment</b> <i>prompt</i>
  <br/>
  &#160;&#160;&#160;&#160;&#160;&#160;<b>depends on</b> <i>expr</i></code></p>

  <p>A comment is used to add a notice to the user during configuration. It is
  also written into the resulting configuration file.</p>

  <p>The comment definition starts with the <code>comment</code> keyword
  followed by the comment prompt (text). For example:</p>

  <pre>comment "IO disabled, no output will be shown"
        depends on !IO</pre>

  <p>Similar to other entries, a comment may specify a number of attributes on
  the following lines. Currently the only valid comment attribute is
  <code>depends&#160;on</code> which can be used to make a comment
  conditional, as shown in the example above.</p>

  <h2 id="lang-source">3.5 Source (<code>source</code>)</h2>

  <p class="code"><code><b>source</b> <i>path</i>
  <br/>
  <br/>
  <i>path</i> = <i>string</i></code></p>

  <p>The source definition is used to source (include) one
  <code>Kconfig</code> file into another. It starts with the
  <code>source</code> keyword followed by the path string.</p>

  <p>For example, if you would like your <code>Kconfig</code> file to reside
  in the root directory of your project (which is customary in several
  projects that use Kconfig, including the Linux kernel), then you can place
  the following line in your <code>build/Kconfig</code> and then write the
  rest of the definitions in the root <code>Kconfig</code>:</p>

  <pre>source "$(SRC_ROOT)/Kconfig"</pre>

  <p>As mentioned in <a href="#iface-func-ext-macro">External Kconfig Macro
  Variables</a>, <code>SRC_ROOT</code> is the pre-defined variable that
  contains the project's source root directory (the same as
  <code>src_root</code> in <code>buildfiles</code>). It should normally be
  used as a base for all your source definitions.</p>

  <div class="note">
  <p>While we can specify a relative path to source, the historic Kconfig
  semantics is to first try to open such a path relative to the current
  working directory. Since <code>build2</code> does not assume any particular
  current working directory, the use of absolute paths based on
  <code>SRC_ROOT</code> is strongly recommended.</p>

  <p>Note also that on Windows all Kconfig paths use forward slashes as
  directory separators, including the <code>SRC_ROOT</code> macro variable.
  You should also use the forward slashes when forming paths based on
  <code>SRC_ROOT</code>, as in the above example.</p>
  </div>

  <p>As another example, consider the following <code>Kconfig</code> fragment
  which is commonly misunderstood:</p>

  <pre>if IO
source "$(SRC_ROOT)/build/Kconfig-io"
endif</pre>

  <p>This is not a conditional inclusion. Rather, it is an unconditional
  inclusion with all the definitions inside <code>Kconfig-io</code> now
  depending on <code>IO</code> (<a
  href="#lang-option-dep">Dependencies</a>).</p>

  <p>There is no conditional inclusion in Kconfig nor, more generally, any
  ability to conditionally exclude a fragment of the <code>Kconfig</code>
  file. The closest we can get is probably a conditional selection of the file
  to source based on the external macro variable. For example, in our
  <code>root.build</code> we could have the following fragment:</p>

  <pre>using cxx

Kconfig.PLATFORM = $cxx.target.class

using kconfig</pre>

  <p>And then in the <code>Kconfig</code> file write the following which would
  include <code>Kconfig-linux</code>, <code>Kconfig-windows</code>, etc.,
  depending on the platform we are targeting:</p>

  <pre>source "$(SRC_ROOT)/build/Kconfig-$(PLATFORM)"</pre>

  <p>Note also that if you are using this technique, then you will need to
  explicitly mention such <code>Kconfig-*</code> files as prerequsites in a
  <code>buildfile</code> in order for them to be included into the
  distribution. For example, in your root <code>buildfile</code> you could
  have:</p>

  <pre>./: ... build/file{Kconfig-*}</pre>

  <h2 id="lang-macro">3.6 Macro Language</h2>

  <p>The Kconfig language provides support for <code>make</code>-like macro
  substitution. Conceptually, there are two languages layered one on top of
  the other: the bottom layer is the macro language that performs plain
  textual substitutions. The result is then used as input to the top layer,
  which is the Kconfig definition language. For example:</p>

  <pre>DEFAULT_GREETING := Hey there

config GREETING
        string "Custom greeting"
        default "$(DEFAULT_GREETING)"</pre>

  <p>After the macro substitution, the top layer will see:</p>

  <pre>config GREETING
        string "Custom greeting"
        default "Hey there"</pre>

  <p>Macro substitutions can appear in pretty much any context, including
  prompts, default values, expressions, and so on. It is, however, important
  to keep in mind that macro variable names and option names/symbols operate
  in different languages. In particular, while a macro variable can contain an
  option name (symbol) it cannot contain an "expansion" (that is, a value) of
  an option. For example, the following does not make sense:</p>

  <pre>GREETING_VALUE = $(GREETING)

config GREETING
        string "Custom greeting"
        default "Hello"</pre>

  <div class="note">
  <p>While this conceptual model is helpful as an understanding aid, this is
  not exactly how the implementation works and there are some restrictions.
  Specifically, Kconfig keywords cannot be the result of the macro
  substitution nor can substitutions span multiple Kconfig tokens. Refer to
  the official <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html">Kconfig
  Macro Language</a> documentation for details.</p>
  </div>

  <p>Macro variables can only be assigned at the beginning of a
  <code>Kconfig</code> file before any Kconfig definitions (options, menus,
  etc). Similar to <code>make</code>, there is no need to quote values in a
  macro variable assignment unless we want the value to contain literal
  quotes. For example, this version is equivalent to the above:</p>

  <pre>DEFAULT_GREETING := "Hey there"

config GREETING
        string "Custom greeting"
        default $(DEFAULT_GREETING)</pre>

  <p>During substitution, the corresponding value is first looked up in the
  variable assignments of the <code>Kconfig</code> file. If not found, then
  the value is looked up in the <code>Kconfig.*</code> Buildfile variables
  with <code>SRC_ROOT</code> being the only pre-defined variable (see <a
  href="#iface-func-ext-macro">External Kconfig Macro Variables</a> for
  details). An undefined variable substitution is an error.</p>

  <p>For example, instead of setting <code>DEFAULT_GREETING</code> in the
  <code>Kconfig</code> file as above, we could set it from
  <code>root.build</code>:</p>

  <pre>Kconfig.DEFAULT_GREETING = '"Hey there"'

using kconfig</pre>

  <p>As another example, we can pass the platform we are targeting as a macro
  variable:</p>

  <pre>using cxx

Kconfig.PLATFORM = $cxx.target.class

using kconfig</pre>

  <p>And then use it in <code>Kconfig</code> to conditionally enable options,
  choose their default values, and so on:</p>

  <pre>config IO
        bool "IO support"
        depends on "$(PLATFORM)" != "windows"

config GREETING
        string "Custom greeting"
        default "Hey" if "$(PLATFORM)" = "linux"
        default "Hello"

comment "Targeting $(PLATFORM)"</pre>

  <p>Note also that due to the two-layer textual substitution semantics all
  variable references are always substituted. For example:</p>

  <pre>config GREETING
        string "Custom greeting"
        default $(DEFAULT_GREETING_IO) if IO
        default $(DEFAULT_GREETING) if !IO</pre>

  <p>In this example, both <code>DEFAULT_GREETING</code> and
  <code>DEFAULT_GREETING_IO</code> must always be defined regardless of which
  default value is (later) used.</p>

  <p>Similar to <code>make</code>, Kconfig supports both simple and
  recursively-expanding variables with the latter used as a building block to
  support functions. For details, refer to the official <a
  href="https://www.kernel.org/doc/html/latest/kbuild/kconfig-macro-language.html">Kconfig
  Macro Language</a> documentation.</p>

  <div class="note">
  <p>The use of the builtin <code>shell</code> function in the context of
  <code>build2</code> is not recommended since it will most likely result in
  portability issues and poor performance.</p>
  </div>

  <h2 id="lang-helper">3.7 Helper Options</h2>

  <p>An option without a prompt or with a prompt that is disabled by <code>if
  <i>expr</i></code> is invisible to the user. However, such an option can
  still take on a default value or be set by <code>select</code> and
  <code>imply</code> (<a href="#lang-option-rev-dep">Reverse Dependencies</a>)
  with the result still usable inside the <code>Kconfig</code> file, for
  example, for other option's dependencies, as well as accessible outside
  through the <code>kconfig.*</code> Buildfile variables. Such options are
  called <i>helper options</i>. For example:</p>

  <pre>choice
        prompt "Greeting"
        default GREETING_HELLO

config GREETING_HELLO
        bool "\"Hello\""
        select GREETING_BUILTIN

config GREETING_HI
        bool "\"Hi\""
        select GREETING_BUILTIN

config GREETING_HOWDY
        bool "\"Howdy\""
        select GREETING_BUILTIN

config GREETING_CUSTOM
        bool "Custom greeting"

endchoice

config GREETING_BUILTIN
        bool</pre>

  <p>In this example <code>GREETING_BUILTIN</code> is a helper option that is
  set to true when one of the builtin greeting strings is selected. It can
  then be used as a dependency for another option, for example:</p>

  <pre>config PUNCT
        string "End of greeting punctuation"
        default "!"
        depends on !GREETING_BUILTIN
        help
          Character for punctuating the end of the custom greeting
          sentence.</pre>

  <p>Continuing with the above example, here is another option that becomes a
  helper if we are using one of the builtin greeting strings:</p>

  <pre>config GREETING_TEXT
        string "Custom greeting" if GREETING_CUSTOM
        default "Hello" if GREETING_HELLO
        default "Hi"    if GREETING_HI
        default "Howdy" if GREETING_HOWDY
        help
          Custom string to use as a greeting.</pre>

  <p>The idea here is that now we have an option that contains the greeting
  string in both the builtin and custom cases. As a result, instead of having
  to write something like this in our <code>buildfile</code>:</p>

  <pre>if $kconfig.hello.greeting_builtin
{
  if $kconfig.hello.greeting_hello
    greeting = 'Hello'
  elif $kconfig.hello.greeting_hi
    greeting = 'Hi'
  elif $kconfig.hello.greeting_howdy
    greeting = 'Howdy'
  else
    fail 'unhandled builtin greeting'
}
else
  greeting = $kconfig.hello.greeting_text</pre>

  <p>We can just have:</p>

  <pre>greeting = $kconfig.hello.greeting_text</pre>

  <h2 id="lang-mod">3.8 Modularity Support</h2>

  <p>The Kconfig language provides support for configuration options that
  besides being selected (<code>y</code>) or not (<code>n</code>) can also be
  selected as a module (<code>m</code>).</p>

  <div class="note">
  <p>While it may be tempting to try to re-purpose this support for something
  similar but not quite the same, modularity in Kconfig is fairly
  purpose-built for the Linux kernel needs and straying too far from its
  intended semantics will likely result in a poor fit.</p>
  </div>

  <p>The central part of this functionality is the <code>tristate</code> type
  which, in addition to the <code>bool</code>'s <code>y</code> and
  <code>n</code> states, has the third <code>m</code> state. When converted to
  the <code>kconfig.*</code> variables, <code>tristate</code> is mapped to the
  <code>string</code> Buildfile type with the <code>true</code>,
  <code>false</code>, and <code>module</code> possible values.</p>

  <p>The availability of this third state is also gated by the
  specially-designated <code>bool</code> option that determines whether
  overall modules support is enabled. Similarly, in expressions (<a
  href="#lang-option-expr">Expressions</a>) <code>m</code> is equivalent to
  <code>y</code> only if modules are enabled. For example:</p>

  <pre>config MODULES
       bool "Modules support"
       modules

config IO
       tristate "IO support"</pre>

  <p>In the above example, <code>MODULES</code> is designated as the modules
  option with the <code>modules</code> attribute. If we answer <code>y</code>
  to <code>MODULES</code>, then for <code>IO</code> we will be able to choose
  between <code>y</code>, <code>m</code>, and <code>n</code>. However, if
  <code>MODULES</code> is <code>n</code>, then our choice for <code>IO</code>
  will be between <code>y</code> and <code>n</code>:</p>

  <pre>$ b configure
Modules support (MODULES) [Y/n/?] (NEW) y
IO support (IO) [N/m/y/?] (NEW)

$ b configure
Modules support (MODULES) [Y/n/?] (NEW) n
IO support (IO) [N/y/?] (NEW)</pre>

  <p>If we want to unconditionally enable modules in our project, then we can
  make the <code>MODULES</code> option prompt-less with <code>y</code>
  default, for example:</p>

  <pre>config MODULES
       bool
       default y
       modules</pre>

  <div class="note">
  <p>Only one configuration option can be designated as the module option.
  This makes it difficult to compose project configuration that use this
  functionality.</p>
  </div>

  <p>Besides normal options, <code>tristate</code> can also be used in
  choices. Such a choice allows the user to select only one option as
  <code>y</code> but more than one as <code>m</code> (again, provided modules
  are enabled). For example:</p>

  <pre>choice
        prompt "Name fallback"

config NAME_ASK
        tristate "Ask for name"
        help
          Ask for the name to greet if it is unspecified on the
          command line.

config NAME_DEF
        tristate "Use default name"
        help
          Use the default name to greet if it is unspecified on the
          command line.

endchoice</pre>

  <h2 id="lang-back-compat">3.9 Backwards Compatibility</h2>

  <p>It is typical and well supported by Kconfig to reuse an old configuration
  when upgrading to a new version of the project (see <a
  href="#iface-func-conf-method">Configuration Methods</a> for details). As a
  result, when evolving a project that uses Kconfig, it makes sense to keep
  backwards compatibility in mind.</p>

  <p>Besides a <i>full</i> old configuration, users of our project can also
  keep <i>minimal</i> default configurations produced with <code>kconfig-conf
  --savedefconfig</code>. Unlike the full configuration which contains all the
  values, default configurations only contain values that differ from the
  defaults. Based on this understanding, these changes normally lead to
  reasonable backwards compatibility:</p>

  <ul>
  <li>Adding new or removing/renaming existing options.</li>

  <li>Moving options around or organizing them into sub-menus.</li>

  <li>Changing dependencies and visibility of existing options, menus,
  etc.</li>

  <li>Changing prompt or help of existing options, menus, etc.</li>
  </ul>

  <p>In contrast, these changes should normally be avoided:</p>

  <ul>
  <li>Changing type of existing options.</li>

  <li>Changing default value or range of existing options.</li>

  <li>Removing existing options from non-optional choices that do not specify
  a default value.</li>
  </ul>

</div>

</body>
</html>
